 (Disk 2).iso/pc/technical publications/quicktime/qtdevdocs/images/qtsmban.gif){kind=small}
 (Disk 2).iso/pc/technical publications/quicktime/qtdevdocs/images/qt4api.gif)
QuickTime 4 Reference
| Previous | Chapter Contents | Chapter Top | Next |
Data handler components provide two basic read facilities. The DataHGetData function is a fully synchronous read operation, while the DataHScheduleData function is asynchronous. Applications provide scheduling information when they call your component's DataHScheduleData function. When your component processes the queued request, it calls the application's data-handler completion function (for more information, see "Completion Function" later in this chapter). By calling your component's DataHFinishData function, applications can force your component to process queued read requests. Applications may call your component's DataHGetScheduleAheadTime function in order to determine how far in advance your component prefers to get read requests.
Before any application can read data from a data reference, it must open read access to that reference by calling your component's DataHOpenForRead function. The DataHCloseForRead function closes that read access path.
For more information on reading movie data, see "Retrieving Movie Data" .
Your component opens its current data reference for read-only access.
pascal ComponentResult DataHOpenForRead (DataHandler dh);
After setting your component's current data reference by calling the DataHSetDataRef function, client programs call the DataHOpenForRead function in order to start reading from the data reference. Your component should open the data reference for read-only access. If the data reference is already open or cannot be opened, return an appropriate error code.
Note that the Movie Toolbox may try to read data from a data reference without calling your component's DataHOpenForRead function. If this happens, your component should open the data reference for read-only access, respond to the read request, and then leave the data reference open in anticipation of later read requests.
Your component closes read-only access to its data reference.
pascal ComponentResult DataHCloseForRead (DataHandler dh);
Your component reads data from its current data reference. This is a synchronous read operation.
pascal ComponentResult DataHGetData (
DataHandler dh,
Handle h,
long hOffset,
long offset,
long size);
The DataHGetData function provides a high-level read interface. This is a synchronous read operation; that is, the client program's execution is blocked until your component returns control from this function. As a result, most time-critical clients use the DataHScheduleData function to read data.
Note that the Movie Toolbox may try to read data from a data reference without calling your component's DataHOpenForRead function. If this happens, your component should open the data reference for read-only access, respond to the read request, and then leave the data reference open in anticipation of later read requests.
Your component reads data from its current data reference. This can be a synchronous read operation or an asynchronous read operation.
pascal ComponentResult DataHScheduleData (
DataHandler dh,
Ptr placeToPutDataPtr,
long fileOffset,
long dataSize,
long refCon,
DataHSchedulePtr scheduleRec,
DHCompletionUPP completionRtn);
The DataHScheduleData function provides both a synchronous and an asynchronous read interface. Synchronous read operations work like the DataHGetData function--the data handler component returns control to the client program only after it has serviced the read request. Asynchronous read operations allow client programs to schedule read requests in the context of a specified QuickTime time base. Your data handler queues the request and immediately returns control to the calling program. After your component actually reads the data, it calls the client program's data-handler completion function.
If your component cannot satisfy the request (for example, the request requires data more quickly than you can deliver it), your component should reject the request immediately, rather than queuing the request and then calling the client's data-handler completion function.
The client program provides scheduling information for scheduled reads in a schedule record. This structure is defined as follows:
typedef struct DataHScheduleRecord {
TimeRecord timeNeededBy; /* schedule info */
long extendedID; /* type of data */
long extendedVers; /* reserved */
Fixed priority; /* priority */
} DataHScheduleRecord, *DataHSchedulePtr;
If the extendedID field is set to kDataHExtendedSchedule , the remainder of the schedule record is defined as follows:
Note that the Movie Toolbox may try to read data from a data reference without calling your component's DataHOpenForRead function. If this happens, your component should open the data reference for read-only access, respond to the read request, and then leave the data reference open in anticipation of later read requests.
The DataHFinishData function instructs your data handler component to complete or cancel one or more queued read requests. The client program would have issued those read requests by calling your component's DataHScheduleData function.
pascal ComponentResult DataHFinishData (
DataHandler dh,
Ptr placeToPutDataPtr,
Boolean cancel);
Client programs use the DataHFinishData function either to cancel outstanding read requests or to demand that the requests be serviced immediately. Pre-roll operations are a special case of the immediate service request. The client program will have queued one or more read requests with their scheduled time of delivery set infinitely far into the future. Your data handler queues those requests until the client program calls the DataHFinishData function demanding that all outstanding read requests be satisfied immediately.
Note that your component must call the client program's data-handler completion function for each queued request, even though the client program called the DataHFinishData function. Be sure to call the completion function for both canceled and completed read requests.
The DataHGetScheduleAheadTime function allows your data-handler component to report how far in advance it prefers clients to issue read requests.
pascal ComponentResult DataHGetScheduleAheadTime (
DataHandler dh,
long *millisecs);
This function allows your data handler to tell the client program how far in advance it should schedule its read requests. By default, the Movie Toolbox issues scheduled read requests between 1 and 2 seconds before it needs the data from those requests. For some data handlers, however, this may not be enough time. For example, some data handlers may have to accommodate network delays when processing read requests. Client programs that call this function may try to respect your component's preference.
Note, however, that not all client programs will call this function. Further, some clients may not be able to accommodate your preferred time in all cases, even if they have asked for your component's preference. As a result, your component should have a strategy for handling requests that do not provide enough advanced scheduling time. For example, if your component receives a DataHScheduleData request that it cannot satisfy, it can fail the request with an appropriate error code.
| Previous | Chapter Contents | Chapter Top | Next |